Windows GDI API Reference - Microsoft Developer Network

Graphics Device Interface (GDI)

The Graphics Device Interface (GDI) is a core Windows component that provides applications with a consistent and device-independent way to represent graphics and text. GDI handles all screen drawing operations, allowing applications to draw lines, curves, text, and bitmaps without needing to know the specifics of the display device.

Core Concepts

Device Contexts (DCs): Objects that encapsulate the properties of a drawing surface (like a screen, printer, or metafile). You draw by selecting "graphics objects" (pens, brushes, fonts, bitmaps) into a DC and then calling drawing functions.
Graphics Objects: Resources used for drawing, including:
- Pens: Define the color, style, and width of lines and borders.
- Brushes: Define the color and pattern used to fill areas and draw text characters.
- Fonts: Specify the typeface, size, and style of text.
- Bitmaps: Raster images.
- Palettes: Maps the colors available on a device to the colors an application needs.
- Regions: Defined areas that can be filled or used for clipping.
Coordinate Systems: GDI uses logical coordinates for drawing, which are then mapped to device coordinates by the system.
Drawing Functions: A rich set of functions for drawing primitives (lines, rectangles, ellipses), text, and images.

Key API Areas

The GDI API is vast, but commonly used areas include:

Device Context Management
Drawing Primitives
Text and Font Operations
Bitmap and Image Handling
Color and Palette Management
Clipping Regions

Device Context Management

Device contexts (DCs) are fundamental to GDI drawing. They are handles to structures containing information about the drawing surface and its associated attributes.

Function	Description
`GetDC()`	Retrieves a device context for a client area of a window.
`GetWindowDC()`	Retrieves a device context for the entire window, including the non-client area.
`CreateCompatibleDC()`	Creates a memory device context that is compatible with the specified device.
`DeleteDC()`	Deletes the specified device context (and releases its system resources).
`SelectObject()`	Selects a graphics object (pen, brush, bitmap, font) into a device context.
`GetCurrentObject()`	Retrieves the handle to the current object of a specified type for a device context.

Drawing Primitives

GDI provides functions to draw basic shapes and lines.

Function	Description
`MoveToEx()`	Updates the current graphics position.
`LineTo()`	Draws a line from the current position to a specified point.
`Rectangle()`	Draws a rectangle.
`Ellipse()`	Draws an ellipse.
`RoundRect()`	Draws a rectangle with rounded corners.
`Polygon()`	Draws a polygon.
`Polyline()`	Draws a series of connected lines.

Text and Font Operations

Render text on the screen with control over fonts and alignment.

Function	Description
`TextOut()`	Writes a string of characters at the specified position.
`ExtTextOut()`	Writes a string of characters using extended options.
`CreateFont()`	Creates a logical font with specified characteristics.
`CreateFontIndirect()`	Creates a logical font based on the characteristics of a `LOGFONT` structure.
`SetTextAlign()`	Sets the text-alignment flags for the current device context.
`GetTextExtentPoint32()`	Calculates the length and height of a line of text.

Bitmap and Image Handling

Load, manipulate, and display bitmap images.

Function	Description
`CreateBitmap()`	Creates a bitmap with the specified dimensions and color format.
`LoadBitmap()`	Loads a bitmap resource from an executable file.
`BitBlt()`	Performs a bit-block transfer of the color data for a specified rectangle from the source device context to a destination device context.
`StretchBlt()`	Copies a bitmap from the source device context to the destination device context, applying GDI scaling.
`GetPixel()`	Retrieves the red, green, blue (RGB) color value of the pixel at the specified coordinates.
`SetPixel()`	Sets the pixel at the specified coordinates to the specified color.

Color and Palette Management

Working with colors and ensuring consistent color display across different devices.

Function	Description
`RGB()`	Constructs an RGB color value from red, green, and blue component values.
`CreatePalette()`	Creates a logical palette.
`SelectPalette()`	Selects a palette into the device context.
`RealizePalette()`	Maps the colors in the specified palette to the colors on the device.

Clipping Regions

Restrict drawing operations to a specific area within a device context.

Function	Description
`CreateRectRgn()`	Creates a rectangular region.
`CreatePolygonRgn()`	Creates a polygonal region.
`CombineRgn()`	Combines two specified regions and stores the result in a third region.
`SelectClipRgn()`	Selects a clipping region into the device context.
`ExcludeClipRect()`	Excludes a rectangular area from the current clipping region.
`IntersectClipRect()`	Intersects the current clipping region with the specified rectangle.

Note on GDI+

While GDI is a foundational graphics API, for more advanced features like anti-aliased graphics, gradients, complex transformations, and support for image formats beyond basic bitmaps, consider using GDI+ (Graphics Device Interface Plus). GDI+ offers a higher-level, object-oriented approach to graphics drawing.